\documentclass[titlepage]{article}

\usepackage{tabularx}
\usepackage{fullpage}
\usepackage{graphicx}
\usepackage[pdfborder={0 0 0}]{hyperref}

\graphicspath{{./gfx/}}

\title{System Design Document\\Colony Management\\(Working Title)}
\author{CIS*3760 Software Engineering\\
\\
Winter 2012\\
\\
School of Computer Science\\
University of Guelph\\
Guelph, ON, Canada\\
%%\vfill
\\
Team members:\\
Chris Allen, 0703391\\
Douglas Griffith, 0506355\\
Jameson Reed, 0666220\\
\\
Clients:\\
Jeremy Simpson, Ph.D.\\
Melissa Allwood, BSc.H
}

\date{}

\begin{document}
\maketitle
\tableofcontents
\clearpage

\section{Revision History}
\subsection*{Revision 1.0}

Initial release, 2012-03-02

\subsection*{Revision 1.1}

Second release, 2012-03-12\\

\noindent Minor fixes.

\subsection*{Revision 1.2}

Third release, 2012-03-26\\

\noindent Minor updates.
\clearpage

\section{Preface}

This document addresses the design of the Colony Management application. The intended audiences for this document are the designers and the clients of the application.

\section{Design Goals}

\subsection{Performance criteria}

\subsubsection{Response time}

Almost every interaction with the application will cause a database transaction. Therefore, the developers will need to ensure efficient database calls along with fast application response times to ensure speedy response times. Each page transition should take less than a second to occur. However, page transitions with a duration greater than one second are acceptable if the page contains a lot more information. 

\subsubsection{Memory}

The application is designed to retain all information entered over time.
The program will start by using a very small amount of system memory.
Over time, as more data will be added to the database, this will cause our physical memory allocation to become larger.
The only way a researcher can cut down on the memory allocation of the application is to manually edit the database backup file produced by the application and then import the file back into the application and update the colony.

\subsubsection{Client concurrency}

This application can be used in groups of various sizes.
Because the application is peer-to-peer instead of a client-server relationship, a researcher can import files from any team member which will then synchronize the researcher's colony state to the most recent state.

\subsection{Dependability criteria}

\subsubsection{Robustness}

The application must be able to detect valid touch gestures that the researcher makes. When the researcher is creating new objects (whether they are new experiments, breeding pairs, etc.), the application must provide validation checks for the input entered into the forms. In some cases the application can force the type of input the researcher can give. An example of such is having a drop-down list for genotypes to select from instead of letting them type the name in on their own.

\subsubsection{Reliability}

All valid touch gestures must have a predictable response from the application.
All data entered into the application must be received correctly.
If there are discrepancies between the information entered and the information taken into the application, this could cause estimation and planning errors when researchers are determining future colony decisions. 

\subsubsection{Availability}

The application is available for as long as the phone has a charge. The researcher can access the data at any time of the day.
 
\subsubsection{Security}

Because this application uses peer-to-peer networking, the researcher should only send information to team members that they trust.
The researcher should enter their correct names and contact information into the program in order to ensure the safe transfer of information.
The transferring of information should be done over trusted networks to ensure safe delivery.
The researchers must also ensure that their phones are secured using their platform-specific functionality when they are not in use in order to secure their data.

\subsection{Cost criteria}

\subsubsection{Deployment}

There should be little to no cost required for deployment. This is because that there are no servers to maintain or costs to host the application. The application will be hosted for free on CMER's website and Apple offers free application hosting for students. These organizations also provide free software distribution services so clients get can access the application without any cost.   

\subsubsection{Maintenance}

In order to keep up the maintenance of the application, the client will need to hire outside sources.
After the semester has been completed, our team will be disbanded and no one will be dedicated to the maintenance of the application.
However, all of the source code and documentation for the application is released under an open source license, and will be provided to the client when the application is complete.
This will allow the client to transition to another development team if necessary without much difficulty.

\subsubsection{Administration}

There will be no administration costs associated with the app. No services are needed to be maintained and backing up data can be done within the application.

\subsection{Maintenance criteria}

\subsubsection{Extensibility}

The system will be designed with minimal coupling so that changes can be made with little hassle. If another team takes over the project they can reference our documentation which follows the correct standards so picking up from where our team left off so be a painless process.

\subsubsection{Portability}

So far the application will only be tested on BBOS version 6+, and iOS version 4+.
So far there are no plans to extend the application to more platforms, but the code should be able to be ported over to other devices with slight modifications.

\subsubsection{Readability}

The application's source code will be developed in a model-view-controller structure and therefore should be easy to read and understand how it functions.
Our team will also conform to coding and documentation standards (standards are pending decision) to help further the readability of the code.

\subsection{End user criteria}

\subsubsection{Utility}

The application will support almost all of the users requirements that were requested. However, ideas like server storage and automatic syncing were rejected due to time restraints.

\subsubsection{Usability}

The application will be very easy to navigate through and the researcher should be able to use it without referencing a manual. The application heavily uses list views with uniform layouts so that it keeps browsing and interactions predictable.

\section{Design Trade-offs}

\subsection{Efficiency vs. portability}

In order to support multiple platforms in a very short period of time, the application will be constructed using web languages.
This allows easier portability as the same code can be ported to all previously mentioned mobile devices instead having to individually develop the application in various native languages.
The downside to this is that interpreted applications are more inefficient compared to their compiled counterparts and therefore will perform slower. 

\subsection{Space vs. speed}

Over a period of time, the application may require a larger amount of physical memory to continue retaining changes made in the system.
The system may become slower because the database calls made and the manipulating of the large amounts of data will take more time to process.
However, researchers can edit out information by editing their database backup on a computer and then reloading it back into the system. 

\subsection{Delivery time vs. quality}

Due to the limited time available to finish the product, the application should work but may not contain the same quality as a professionally done product.

\subsection{Reliability vs. cost}

The application must be reliable because if there are any mistakes that go unseen, they can effect the future information entered into the system.
The application is designed to remove estimation mistakes made by researchers and therefore mistakes would make it useless.
Since there are no fees tied to the development of this application, the reliability is dependant on how much time the team can contribute to the product. 

\section{System Decomposition}

\subsection{Subsystems}

The system has been broken down into a series of datatype subsystems, a scheduler subsystem, and a back-end subsystem.
The datatype subsystems are  based on the structural/hierarchical division of the data, but they themselves are not related in any fashion hierarchical or otherwise.
These datatype subsystems only handle the functionality related to their datatype.
The scheduler subsystem handles the scheduling logic, and the back-end subsystem brings it all together allowing access to the data storage and providing a control system between the datatype subsystems. 

\begin{figure}[htb]
\centering
\includegraphics[keepaspectratio,height=0.7\textheight,width=\textwidth]{Packagesubsystem}
\caption{Subsystem diagram}
\end{figure}

\subsubsection{Colony}
The Colony subsystem handles all of the colony level functionality.
This includes: creation of a colony, removal of a colony, and colony level attributes, displaying colony information and navigation to a colony, and initiating data transfers.

\subsubsection{Experiment}
The Experiment subsystem handles all of the experiment level functionality.
This includes: creation and deletion of experiments, viewing and editing experiments, and navigation between experiments. Furthermore, the experiment subsystem will also handle the functionality relating to experiment control groups. 

\subsubsection{Mouse}

The Mouse subsystem handles all of the mouse level functionality. This includes: creation and deactivation of mice, viewing and editing their attributes.

\subsubsection{Litter}

The Litter subsystem handles all of the litter level functionality. This includes: adding new litters, editing the litters information, removing litters, and navigation between litters.

\subsubsection{TeamMember}

The TeamMember subsystem handles all of the team member related functionality. This includes: adding team members, editing their attributes, and removing team members. 

\subsubsection{BreedingPair}

The BreedingPair subsystem handles the breeding pair related functionality. This includes: adding breeding pairs, editing breeding pairs, retiring breeding pairs, and navigating through breeding pairs.

\subsubsection{Scheduler}

The Scheduler subsystem handles the logical work that needs to be done relating mice with experiments, it can access data for both the experiments and mice.
It is controlled by the back-end and initiated when a subsystem has caused a change that requires its attention.

\subsubsection{Back-end}

The back end is the subsystem that binds it all together, it provides each of the data type subsystems access to systems stored data, and when the users actions require a transfer to the next data type subsystem the back-end handles the transfer of any relevant state such as the working colony to the new subsystem.

\subsection{Layers and partitions}

The subsystems do not fit the typical idea of a hierarchy. The subsystems are not organized based on the layer components they contain, instead they are divided based on functional groupings, each of which will have complete control of the system when its active. There is no top level subsystem running the show and subsystems do not retain state when they are inactive.

\begin{figure}[htb]
\centering
\includegraphics[keepaspectratio,height=0.7\textheight,width=\textwidth]{layers}
\caption{Layer diagram}
\end{figure}

\subsubsection{Model}

The model layer is composed of the data storage component of the back end subsystem, and the scheduling subsystem. This layer handles the storage of data and supplies it to the control when requested.

\subsubsection{View}

  The user interface layer is composed of all the views from each data type subsystem, these views allow the user to see the information the subsystem handles and interact with it according to the requirements.

\subsubsection{Control}

The control layer is composed of all the control components from each of the data type subsystems, as well as the transfer logic from the back end.
This layer handles processing user events the views pass down to it, fetching required data from the back end, and changing between views and subsystems.
 
\subsection{System topology}

As can be seen in the deployment diagram (Figure~\ref{fig:deployment}) the system is deployed in its entirety to a single node, the phone, and data from the application can be transferred between instances of the application via the users email provider of choice.
However this is set up by the user and no data transfer hardware is deployed with the software.

\begin{figure}[htb]
\centering
\includegraphics[keepaspectratio,height=0.7\textheight,width=0.5\textwidth]{deployment}
\caption{Deployment diagram}
\label{fig:deployment}
\end{figure}

\section{Concurrency Identification}

The system does not support multiple users editing the same set of data concurrently.
Furthermore the application is single threaded with only one subsystem being in control at any time, and as such there is no risk of concurrent access to persistent data storage. 

The multiple user support the system provides is the ability for a user to add an email list of team members which they can quickly send an export of one of their colony data sets to.
A team member receiving an export can choose to import the received colony data set and proceed to work on their new independent copy of the data.
It is up the users to keep track of who has the most up to date edition of the data, and ensure they are not working with and out of date copy.

\section{Hardware/Software Allocation}

The application is developed for mobile devices and therefore the capabilities of the application given the restraints of each mobile device will need to be considered. We are targeting two different mobile platforms: BBOS 6+ (BlackBerry Bold 9900), and iOS 4+ (iPhone 4). Depending on time the application could possibly be designed to conform to the unique traits of the BlackBerry Curve or Torch lines because they also use BBOS 7.

\subsection{System performance}

Each selection that the researcher makes should yield results within seconds. However, since almost all interactions in the application create database calls, the program is also dependant upon the response time of the database. This could become an issue much later on as the database will constantly be growing with time and getting that information from the database will cause more waiting.

\subsubsection{I/O performance}

Because all interactions with the application are done locally on the mobile device, the program should work as fast as the device will allow it. This means all interaction should be very responsive and keep up with the speed of the researcher.

\subsubsection{Processor allocation}

The application will not be stressful on the mobile device's processor. The processors found on all supported devices should easily be able to handle the performance requirements of this application.

\subsubsection{Memory allocation}

The mobile device should have enough memory to support the application.
As mentioned in the previous section, the application retains all the data entered.
If the researcher does not manually remove older data from the application from a computer, the file size will grow and space on the device is a factor.
All devices that this application is designed for have multiple gigabytes of storage so this should not be an immediate problem.

\subsection{Connectivity}

Connectivity is done by a peer-to-peer format.
There is no server connecting the client applications, so the synchronization of data is dependant on sending and receiving data packets to one another.
This is done by exporting data to an attachment on an e-mail and then mailing it to the other researchers.
The receiving researchers import the file and it will update their colony data.
A researcher can also export the backup data in a spreadsheet compatible format to their computer and keep track of the colonies from there.

\subsection{Network architecture}

How secure the data packages are when being transferred is completely dependant on the researcher's e-mail client's security or the security of the computer the researchers are using to backup data.   

\section{Data Management}

\subsection{Persistent data storage}

The system will store persistent data in two forms: a relational database and flat files.  
The relational database will be used for read-write and query operations while the application is executing.
Flat files will be used for write-once backups/exports.
The flat files will be used to transfer information between Team Members, and they also function as backups, allowing users to re-import their own data in case of hardware failure or other circumstances.

\subsection{Data backups}

Data in the system is not automatically backed up or distributed in any fashion. The user must decide when they wish to perform a backup operation.

\subsection{Persistent data access}

Each database will only have one user, so the query rate will be very low on average.
Instances when the query rate will exceed the average are: importing/exporting data, and performing rescheduling operations.
The database is only accessed when the user is actively using the application, which might be several times per day.
Depending on the size of the colony and how much history data is stored, queries could return anywhere between $<$1KB and $>$1MB of data.
The worst case would be exporting a database, where the size of the query would be equal to the size of the database.

Implementation details of the database/flat file and the query format must be restricted to Control objects, so the rest of the application will be agnostic with regard to the specifics of the data-store.

Queries must be written to the SQL-92 standard whenever possible, to ensure portability. When vendor-specific extensions are used they must be commented and documented appropriately.
All queries must be written using transactions, to ensure data integrity.

\section{Global Resource Handling}

The application has no security measures and depends on the security of the researcher's mobile device. Therefore the researcher has full access to the data contained inside the application without having to provide credentials. As long as the user is using one of the valid devices which supports touch gestures, the researcher will receive full access.

\section{Software Control Implementation}

\subsection{External control flow}
\label{sec:external_control_flow}

Because the application is self-contained and does not require a centralized server, nothing external will be controlling the program and  all operations and data storage is done within the application.

\subsection{Concurrent control}

It is up the the researchers to retain concurrency. If researchers are working on different projects, they can both continue working on separate projects and later combine their data using the application exporting service. Every imported file, after given consent to import, will overwrite everything in a colony that is specified in the import file.

\subsection{Internal control}

As mentioned in \ref{sec:external_control_flow}, all control is done within the application. 

\subsection{User interface}

The application will be designed using the model-view-controller architecture. The control is split into many classes which handle various aspects of the application. For example, we will have one controller class governing all interaction with the experiments of the colony. The view will also be broken into various styles which will be used in multiple parts of the application. For example, showing a list of experiments will look the same as a list of breeding pairs (ignoring the actual content of these objects) and thus the same view will be used with minor changes.

\section{Boundary Conditions}

\subsection{Initialization}

There are two application start-up scenarios: pre-database setup and post-database setup.  
The first scenario is expected when the application is started for the first time, in the event the database is corrupted, or if the database is erased.  
The second scenario is expected to be the majority of start-up cases, when the application is in normal use.

\subsubsection{Pre-database}

If the database does not exist, it must be created using the most recent schema version, and initialized with the example data-set.

\subsubsection{Post-database}

If the schema version of the database matches the schema version of the application, no special action is required and the application will start as normal.

If the schema version of the database is an earlier version than the application version, the user will be allowed to backup the current database and asked whether they wish to execute a database schema upgrade procedure.
If they do not agree to upgrade the database schema, the application will terminate, as application execution is undefined with differing schema versions.

If the schema version of the database is a later version than the application version, the user will be notified that they should be using a later version of the application and terminate.

\subsubsection{User interface}

The user interface presented at start-up time is identical to that at which they exited the application, minus any unsaved changes the user may have made.
Only changes that are persisted to the database are preserved.
The system will present itself to the user as normal in most cases, the only exceptional cases are the pre-database start-up and mis-matched schema start-up.
Pre-database start-up and higher schema version do not require any input from the user, but the user will be informed.
Lower schema version requires the user decide whether they wish to upgrade the database schema or not.

\subsection{Termination}

\subsubsection{Subsystem termination}

The application is single-threaded, so subsystems are not allowed to terminate. The application will always be in one of two states: waiting for user input, or performing work based on user input.

\subsubsection{Application termination}

We assume that the operating system of the device will be able to suspend the application and resume it in the same state. This allows unsaved work to persist in memory when multi-tasking. In the event the application is terminated, unsaved work will be discarded since all data must be validated by the application before being committed to the database, and it must be explicitly requested by the user, except for the application state stack.

\subsection{Failure}

\subsubsection{Abnormal termination}

In the event the application is terminated abnormally, the only data lost would be any unsaved work on the current page.
The application will initialize as normal the next time the application is started.

\subsubsection{Database corruption}

In the event of database corruption, there is no automatic recovery mechanism.
If the database cannot be loaded normally, the application will initialize as if in the pre-database scenario and create a new database from scratch.
Users will then be able to restore manually from database backups.

\subsubsection{Executable corruption}

In the event of application executable data corruption, there is no automatic recovery mechanism, and no automatic detection mechanism.
If erratic application behaviour is observed, the only recourse is to uninstall and re-install the software.
No reasonable predictions can be made about system initialization in the event of executable corruption.

\section{Design Rationale}

\subsection{Design issues}

\subsubsection{Coupling and coherence}

One of our major design issues was with regard to how coupled our various subsystems should be.
Our first design iteration had a very high degree of coupling between the various subsystems, as this would allow the subsystems to share functionality easier.
However, it would also make development more difficult, as most of the system would be contained within several source files.

\begin{description}
	\item[Advantages]
	\item --- Allows development according to the classical object-oriented model (e.g. Java).
	\item --- Fewer source files in total for the application.
	\item --- Theoretically higher performance, as the application does not need to re-instantiate objects.
\end{description}
\begin{description}
	\item[Disadvantages]
	\item --- Very highly coupled, changes may have unforeseen side-effects
	\item --- More difficult to test, as more state needs to be accumulated per test
	\item --- Developers would need to keep the entirety of the system in mind while developing
\end{description}

In the end, we decided on highly decoupled subsystems, where common functionality is discovered during development, abstracted, and shared between developers.

\subsubsection{Abstract attributes}

One design we considered was abstracting the concept of an attribute within the system.
Rather than having a `tag' attribute, or a `genotype' attribute, for each Colony within the application you would be able to add your own attributes, depending on the kind of colony you were managing.
Attributes would be of several different types, including: string, integer, string tuple, and real.
Attributes would be able to be defined with attributes of their own, including: uniqueness within colony, numerical range, string length, required upon creation, and possibly more.

\begin{description}
	\item[Advantages]
	\item --- Allows the system to fit a wide range of possible users.
	\item --- Allows users to customize the system after deployment.
\end{description}
\begin{description}
	\item[Disadvantages]
	\item --- Complex and error-prone implementation.
	\item --- Requires an abstract user interface, so interfaces specific to the problem-domain are not possible.
	\item --- Requires users to specify their required attributes for each colony they create.
\end{description}

In the end we decided on customizing the application to the specific problem-domain of our client, so as to provide them the best user experience possible, and also to meet our development deadlines.

\subsection{Rejected proposals}

One design proposal that was presented was a hybrid architecture design.
The application itself would be standalone, as in the current design, but it would also be able to communicate with an external server to synchronize and merge updates from other team members.

\begin{description}
	\item[Advantages]
	\item --- Very easy to synchronize with other team members.
	\item --- Keeps the advantages of the standalone application.
\end{description}
\begin{description}
	\item[Disadvantages]
	\item --- Requires upkeep and maintenance of an external server.
	\item --- Requires an authentication mechanism between clients and server.
	\item --- Requires the application to manage conflicting updates from the server.
\end{description}

In the end, we decided against this architecture in order to meet our development schedule.

\subsection{Technology enablers}

\subsubsection{Bluetooth}

Bluetooth is a close-range wireless communication technology that is present in most modern smartphones.
It allows smartphones to communicate with various peripheral devices such as headsets, speakers, keyboards, mice, and more.
It also allows smartphones to communicate directly with one another, without the need of a cellular or WiFi network.

Given more development time, we would be interested in using Bluetooth to synchronize devices between team-members, as this offers a convenient method to do so.
However, the development interfaces for each device is very specific, which requires a large amount of testing on real devices to implement it effectively.

\subsubsection{Near field communication}

Near field communication is a very-close-range wireless communication technology that is present in very recent modern smartphones.
It allows smartphones to communicate with one another directly, as well as interrogate RFID tags.
Since there are not many smartphones using this technology at the moment it is not very feasible to use it for synchronization, but it would be useful to implement with regard to management of colonies.
Since RFID tags are rather inexpensive, it would not be difficult to tag each cage, or even each mouse within a colony and use your smartphone to read the tag and retrieve previously stored data associated with the tag.
This would probably be most useful in very large colonies, but it would also be convenient for small colonies.

As with Bluetooth, vendor implementations are very specific, which requires a large amount of real-world testing, and makes it difficult to target more than one platform.
Given more development time, we would be interested in pursuing this technology.

\subsection{Scalability}

\subsubsection{User scalability}

The only metric that makes sense for our system is the scalability of number of users within a team, since there is no upper limit on the number of teams that could exist.

Since our synchronization method is by email, it relies on a number of factors outside our control, which includes operating system limits on email, the user's mail server email limits, and more.
The two limits that are most obvious are mail attachment size, and the number of recipients.
For the current system, I believe any more than 10 users would become unmanageable due to the number of emails required for synchronization.

\subsubsection{Device scalability}

There are no issues with device scalability, as it may be installed and import a recent database backup on any device that it is compatible with.

\subsubsection{Communication scalability}

The system will not automatically be able to take advantage of new communication technologies such as Bluetooth or Near field communication, but any TCP/IP link that allows users to send email will allow the system to synchronize with team members.

\subsection{Extensibility}

\subsubsection{Data types}

The system is fairly extensible with the addition of new data types, but they require new interface widgets, validation code, database schema modification, and of course testing.

\subsubsection{Legacy data}

Any legacy data can be manually entered into the application through the user interface, or converted to the database import format and loaded that way.
There are no plans to develop any sort of automatic conversion utility, as current data is rather user-specific and not well specified.

\subsection{Modifiability}

\subsubsection{Platform stability}

The hardware platform is very unstable, as new smartphone devices are constantly released with faster processors, more memory, and larger screens.
The software platform is also developing fairly rapidly, as the World Wide Web Consortium updates their HTML5 and ECMAScript (JavaScript) standards, and browsers implement them.
However, the majority of these changes are backwards-compatible, which means that targeting HTML5/JavaScript as our platform should allow us to migrate our application fairly easily to new devices and new device operating system versions, as long as the browser component of these systems is relatively standards-compliant.

\subsubsection{Technological advances}

The most interesting technological advance from our perspective would be Near field communication, as more ubiquitous implementation of this standard would allow us to implement a useful new feature.
Most other advances in terms of processor speed, screen size, and general hardware only allow the system to run faster, they do not enable us to implement new features.
An alternative to Near field communication that would be interesting is better image recognition technology and optical character recognition, as this would save the user some manual typing and increase the usability of the interface.

\clearpage
\section{Glossary}

\begin{description}
\item[BBOS ---] BlackBerry Operating System, the operating system present on modern BlackBerry Phones.
\item[Breeding Pair ---] A pair of mice designated for breeding purposes. Kept aside from the rest of the colony.
\item[Colony ---] A colony is a group of mice which will be monitored and used to breed mice fitting desired criteria for experimental use.
\item[Control Group ---] Control groups are used by experiments in order to obtain the desired mix of mice traits. An example of this would be an experiment needing a group of ten females, and another group of 8 males.
\item[Database ---] Collects and retains data used for [Application] and remains inside the phone until the deletion of the application. 
\item[DOB ---] Date of Birth.
\item[Duration ---] An amount of time after the researcher has started a mouse in the experiment before they have to check up on them at the finish.
\item[Experiment ---] A test or series thereof which the researchers would like to accomplish using the mice in their colony.
\item[Genotype ---] A classification of the mice used in creating control groups for experiments, mice genotypes are obtained by sending samples to a test lab.
\item[iOS ---] Apple's iPhone, iPad, and iPod operating system.
\item[Litter ---] A group of pups from a single birth. 
\item[Peer-To-Peer ---] Also known as P2P where devices make direct contact with one another instead of going through a medium like a file server.
\item[PhoneGap ---] A cross platform mobile development framework which allows developers to program in web languages and renders them into the native language of the device.
\item[Pup ---] A newborn mouse.
\item[Researcher ---] The person maintaining the colony and performing experiments.
\item[Research Lab ---] The location where the colonies are kept, and work with the mice is performed.
\item[Test Lab ---] Refers to to the location mice samples are sent for genotype analysis, or the room in which the colonies are kept.
\end{description}

\end{document}
